home *** CD-ROM | disk | FTP | other *** search
/ Almathera Ten Pack 3: CDPD 3 / Almathera Ten on Ten - Disc 3: CDPD3.iso / scope / 126-150 / scopedisk146 / curses / curses.doc < prev    next >
Text File  |  1995-03-19  |  11KB  |  400 lines
  1.             AMIGA CURSES PACKAGE
  2.             ====================
  3.  
  4. Author : Simon John Raybould    (sie@fulcrum.bt.co.uk)
  5. Date   : 21st April 1990
  6.  
  7.  
  8.     This is a brief description of the curses functions provided by this
  9. package. I have not gone into great detail as I assume the users of this to
  10. already have a knowledge of UN*X curses, more than likely porting UN*X screen
  11. based applications to the Amiga. There is plenty of curses documentation
  12. about so I will only outline each of the functions provided.
  13.  
  14.     Cheers
  15.  
  16.         Sie
  17.  
  18.  
  19.  
  20.  
  21. Below is a list of the supported functions and there operation.
  22. ===============================================================
  23.  
  24.  
  25. initscr()
  26.  
  27.     This is usually the first function called by a program. It creates
  28.     stdscr and must be called before any of the other functions will work.
  29.  
  30.  
  31. endwin()
  32.  
  33.     This should be called before exiting a curses program.
  34.     It frees all memory used and dismantles all structures.
  35.     It closes the custom screen and window used.
  36.  
  37.  
  38. beep()
  39.  
  40.     Produces an audible beep from the speaker.
  41.  
  42.  
  43. flash()
  44.  
  45.     Flashes the display, this is instead of, or as well as an audio beep.
  46.  
  47.  
  48. box(window, vertical, horizontal)
  49.  
  50.     Draws a box around the edge of the window.
  51.     window     - pointer returned from newwin or subwin, or stdscr even.
  52.     vertical   - character to use for the verticals.
  53.     horizontal - character to use for the horizontals.
  54.  
  55.  
  56. cbreak()
  57. nocbreak()
  58.  
  59.     cbreak() puts the terminal into CBREAK mode, making characters typed
  60.     available immediately.
  61.  
  62.     nocbreak() sets NOCBREAK mode and characters are not available until
  63.     a newline is typed.
  64.  
  65.     The default is NOCBREAK mode, so most programs call cbreak() before
  66.     doing any reads on the keyboard.
  67.  
  68.  
  69. clearok(WinPtr, flag)
  70.  
  71.     If flag is TRUE then this function will make every refresh clear the
  72.     display before updating it. If the flag is FALSE then the screen will
  73.     not be cleared on each refresh. The DEFAULT is FALSE.
  74.  
  75.  
  76. leavok(window, flag)
  77.  
  78.     If flag is TRUE then the cursor will not be displayed.
  79.  
  80.  
  81. newwin(lines, cols, beg_line, beg_col)
  82.  
  83.     Creates a new window at line 'beg_line' and column 'beg_col'.
  84.     The size of this window is 'lines' lines of 'cols' columns.
  85.  
  86.  
  87. subwin(orig, lines, cols, beg_line, beg_col)
  88.  
  89.     Creates a new window within another window. The original window has
  90.     its pointer passed as 'orig'.
  91.     The new window will be at line 'beg_line' and column 'beg_col' of the
  92.     window pointed to by 'orig'. It will be of size 'lines' lines of 'cols'
  93.     columns.
  94.  
  95.  
  96. delwin(window)
  97.  
  98.     Deletes a window and frees the associated memory. This should be done if
  99.     the window is no longer used.
  100.  
  101.     It is not necessary to free all windows, endwin() will free all windows
  102.     (including stdscr) before returning.
  103.  
  104.  
  105. nl()
  106. nonl()
  107.  
  108.     nl() - Causes newline to newline/carriage return mapping on output and
  109.     return to newline mapping on input.
  110.  
  111.     nonl() - disables this.
  112.     The DEFAULT is that mapping is done.
  113.  
  114.  
  115. echo()
  116. noecho()
  117.  
  118.     echo() causes every character read to be echoed back to the display.
  119.     noecho() prevents the echo, this is useful when reading movement keys,
  120.     you don't want them echoed to the screen.
  121.     The DEFAULT is that echoing is performed.
  122.  
  123.  
  124. nodelay(window, flag)
  125.  
  126.     nodelay is enabled by a call : nodelay(stdscr, TRUE);
  127.     When in nodelay mode, getch will return -1 if there is no input pending.
  128.     The DEFAULT is nodelay FALSE and getch will wait for at least one char
  129.     in CBREAK mode or a newline otherwise.
  130.  
  131.  
  132. has_colors()
  133. start_color()
  134. init_color(n, r, g, b) 
  135.  
  136.     has_colors() is to check if colours are available on this terminal.
  137.     On the Amiga, it will simply return TRUE.
  138.  
  139.     start_colour() is to tell the terminal that you wish to use colour.
  140.  
  141.     init_color() will alter the Red, Green and Blue content of colour n.
  142.     r, g and b are in the range 1 to 1000. The colour number 'n' is in the
  143.     range 0 to 15 and it should be noted that colour 0 is the background
  144.     colour. Initially the foreground is set to colour 1 but can be changed
  145.     with the attron() or attrset() function to any of the colours 1 to 15,
  146.     0 is not allowed as this is the background. If 0 is selected, the
  147.     foreground colour will be set to 1.
  148.  
  149.  
  150. keypad(window, flag)
  151.  
  152.     if flag is TRUE then this will enable use of the function keys and the
  153.     cursor keys. The DEFAULT is that the special keys are not read.
  154.     So to allow use of special keys one will need to add a line similar to:
  155.  
  156.         keypad(stdscr, TRUE);
  157.  
  158.  
  159.     NOTE NOTE NOTE
  160.  
  161.         SPECIAL KEYS ARE NOT SUPPORTED IN THIS VERSION OF AMIGA CURSES
  162.  
  163.  
  164. printw(fmt, args)
  165. wprintw(window, fmt, args)
  166. mvprintw(line, col, fmt, args)
  167. mvwprintw(window, line, col, fmt, args)
  168.  
  169.     Offer formatted output similar to printf(3).
  170.     printw() - prints at the current position in stdscr.
  171.     wprintw() - prints at the current position in window.
  172.     mvprintw() - prints at line 'line' column 'col' in stdscr.
  173.     mvwprintw() - prints at line 'line' column 'col' in 'window'.
  174.  
  175.  
  176. scanw(fmt, args)
  177. wscanw(window, fmt, args)
  178. mvscanw(line, col, fmt, args)
  179. mvwscanw(window, line, col, fmt, args)
  180.  
  181.     Offer formatted input similar to scanf(3).
  182.     scanw() - scans at the current position in stdscr.
  183.     wscanw() - scans at the current position in window.
  184.     mvscanw() - scans at line 'line' column 'col' in stdscr.
  185.     mvwscanw() - scans at line 'line' column 'col' in 'window'.
  186.  
  187.  
  188. scrollok(window, flag)
  189.  
  190.     When flag is true, curses will automatically scroll the window up one
  191.     line when output goes off the bottom.
  192.     E.g.
  193.             scrollok(stdscr, TRUE);
  194.     
  195.     stdscr will then be automatically scrolled up one line when output goes
  196.     off bottom of stdscr.
  197.     The DEFAULT is that the window will NOT be scrolled, the bottom line
  198.     will be used over and over again without scrolling.
  199.  
  200.  
  201. scroll(window)
  202.  
  203.     The window is scrolled up one line.
  204.  
  205.  
  206. setscrreg(top, bottom)
  207. wsetscrreg(window, top, bottom)
  208.  
  209.     Sets the region from line 'top' to line 'bottom' inclusive.
  210.     When output moves below line 'bottom', the region is scrolled up one line
  211.     ( if scrollok() has been called ).
  212.  
  213.  
  214. touchwin(window)
  215.  
  216.     Will force the window to be completely refreshed on the next call to
  217.     refresh by dumping all optimisation information. This can be useful if
  218.     the state of the screen is unknown or if a window was obscured by
  219.     another window which was not a subwindow of the one it covered. Then
  220.     you may need to touchwin() the window that was covered and refresh it.
  221.     
  222.  
  223. addch(c)
  224. waddch(window, c)
  225. mvaddch(line, col, c)
  226. mvwaddch(window, line, col, c)
  227.  
  228.     addch(c) - Prints character c at current screen position in stdscr.
  229.     addch(window, c) - Prints character c at current screen position in
  230.             window.
  231.     mvaddch(line, col, c) - Prints character c at line 'line' column 'col' in
  232.             stdscr.
  233.     mvwaddch(window, line, col, c) - Prints character c at line 'line' column
  234.             'col' in window.
  235.  
  236.  
  237. addstr(str)
  238. waddstr(window, str)
  239. mvaddstr(line, col, str)
  240. mvwaddstr(window, line, col, str)
  241.  
  242.     addstr(str) - Prints string str at current screen position in stdscr.
  243.     waddstr(window, str) - Prints string str at current screen position in
  244.             window.
  245.     mvaddstr(line, col, str) - Prints string str at line 'line' column 'col'
  246.             in stdscr.
  247.     mvwaddstr(window, line, col, str) - Prints string str at line 'line'
  248.             column 'col' in window.
  249.     
  250.  
  251. attrset(attrs)
  252. wattrset(window, attrs)
  253.  
  254.     These routines set the attributes for stdscr or the specified window in
  255.     the case of wattset() to the value passed in attrs. This is usually used
  256.     to get the attributes to a known state before using attron() and
  257.     attroff() to add and remove extra attributes respectively.
  258.  
  259.  
  260. attron(attrs)
  261. wattron(window, attrs)
  262.  
  263.     These routines add the attributes specified in attrs to those already set
  264.     for stdscr or the window specified in the case of wattron(). Any previous
  265.     attributes that are not directly affected by the changes will be left as
  266.     they were.
  267.  
  268.  
  269. attroff(attrs)
  270. wattroff(window, attrs)
  271.  
  272.     These routines remove the attributes specified in attrs from those set
  273.     for stdscr or the window specified in the case of wattroff().
  274.     Any previous attributes that are not directly affected by the changes
  275.     will be left as they were.
  276.  
  277.         e.g.
  278.                 attron(A_REVERSE)
  279.                 addstr("This is in inverse");
  280.                 attroff(A_REVERSE);
  281.                 refresh();
  282.  
  283.  
  284. standout()
  285. wstandout(window)
  286.  
  287.     These routines make the following text appear in inverse video.
  288.  
  289.  
  290. standend()
  291. wstandend(window)
  292.  
  293.     These routines will return the text type to normal video.
  294.  
  295.  
  296. clear()
  297. wclear(window)
  298.  
  299.     These routines will empty the screen buffer and will cause the screen
  300.     to be cleared on the next call to refresh().
  301.  
  302.  
  303. erase()
  304. werase(window)
  305.  
  306.     These routines will empty the screen buffer and will cause the screen
  307.     to be cleared on the next call to refresh(). Similar to erase() except
  308.     that these will call clearok() as well.
  309.  
  310.  
  311. clrtobot()
  312. wclrtobot(window)
  313.  
  314.     On the next refresh(), the window will be blanked from the current
  315.     position to bottom righthand corner.
  316.  
  317.  
  318. clrtoeol()
  319. wclrtoeol(window)
  320.  
  321.     On the next refresh(), the window will be blanked from the current
  322.     position to the end of the line.
  323.  
  324.  
  325. delch()
  326. wdelch(window)
  327. mvdelch(line, col)
  328. mvwdelch(window, line, col)
  329.  
  330.     These routines delete the character at the current position, the rest of
  331.     the line to the right of this character is slid along to the left to
  332.     fill the gap. This can be very useful in editors and the like.
  333.  
  334.  
  335. getch()
  336. wgetch(window)
  337. mvgetch(line, col)
  338. mvwgetch(window, line, col)
  339.  
  340.     These routines return the next character from the keyboard. If cbreak()
  341.     has been called then they return as soon as there is a character to read
  342.     else they wait for a <CR> before returning. If nodelay() has been called
  343.     then they will return a character if there is one or -1 if not.
  344.  
  345.  
  346. getstr()
  347. wgetstr(window)
  348. mvgetstr(line, col)
  349. mvwgetstr(window, line, col)
  350.  
  351.     These routines should be used to read a string in from the keyboard.
  352.     Delete is processed for you.
  353.  
  354.  
  355. inch()
  356. winch(window)
  357. mvinch(line, col)
  358. mvwinch(window, line, col)
  359.  
  360.     These routines return the character at the current position in the
  361.     window or at the specified position in the 'mv' cases.
  362.  
  363.  
  364. insch()
  365. winsch(window)
  366. mvinsch(line, col)
  367. mvwinsch(window, line, col)
  368.  
  369.     These routines insert a character at the current window position, or at
  370.     the specified position in the 'mv' cases. The remainder of the line is
  371.     shifted along to the right to make room. The character at the far right
  372.     is lost.
  373.  
  374.  
  375. insertln()
  376. winsterln(window)
  377.  
  378.     These routines insert a line at the current window position.
  379.     All of the lines below are shifted down and the bottom line is lost.
  380.  
  381.  
  382. deleteln()
  383. wdeleteln(window)
  384.  
  385.     These routines delete a line at the current window position.
  386.     All of the lines below are shifted up into the space and the bottom line
  387.     is left blank.
  388.  
  389.  
  390. move(line, col)
  391. wmove(window, line, col)
  392.  
  393.     These routines set the current position to line 'line' and column 'col'.
  394.  
  395. refresh()
  396. wrefresh(window)
  397.  
  398.     These routines cause all outstanding changes to 'stdscr' or the specified
  399.     window 'wrefresh' to be sent to the screen.
  400.